{literal}
<h2>Annotation</h2>
@orm plugin DomArFile(<br>
&nbsp;&nbsp;&nbsp;[allowedExtensions={ext1[, ..]},]<br>
&nbsp;&nbsp;&nbsp;[root=String,<br>
&nbsp;&nbsp;&nbsp;[rootUrl=String,]<br>
&nbsp;&nbsp;&nbsp;[relative=String,]<br>
&nbsp;&nbsp;&nbsp;[autoRename=String $mask,]<br>
)<br>

<table cellpadding="4" cellspacing="0" border="1">
	<tr>
		<td>allowedExtensions</td>
		<td>Which file extensions are allowed in this list. Sample {doc,txt,xls}</td>
	</tr>
	<tr>
		<td>root</td>
		<td>path to where files will be saved. Default is DOMAR_FILE_DEFAULT_PATH</td>
	</tr>
	<tr>
		<td>rootUrl</td>
		<td>url from where files can be accessed. Default is DOMAR_FILE_DEFAULT_URL<br> If you want root to be in hidden folder (Not accessible via url) then set it to empty string.</td>
	</tr>
	<tr>
		<td>relative</td>
		<td>This will be added to root and rootUrl. You might want to use this if you want to use default root and rootUrl.</td>
	</tr>
	<tr>
		<td>autoRename</td>
		<td>Auto renames file name when holding object is saved. Very useful feature. See detailed description below.</td>
	</tr>
</table>

<h2>Keywords</h2>
When using DomArFile you should know what these keywords mean.
<table cellpadding="4" cellspacing="0" border="1">
	<tr>
		<th>Root</th>
		<td>DomArFile logical root path to where files are moved, copied or uploaded.</td>
	</tr>
	<tr>
		<th>Relative path</th>
		<td>Relative path from root path.</td>
	</tr>
	<tr>
		<th>filename</th>
		<td>Real filename without extension</td>
	</tr>
	<tr>
		<th>extension</th>
		<td>File extension, for example doc, txt etc..</td>
	</tr>
</table>
<h3>Sample 1 </h3>
Full path: <b>/data/home/myDir/image.jpg</b><br>
Root: <b>/data/home/</b><br>
Relative: <b>myDir/</b><br>
filename: <b>image</b><br>
extension: <b>jpg</b><br>
<br>
<h3>Sample 2 </h3>
Full path: <b>/data/home/myDir/image.jpg</b><br>
Root: <b>/data/</b><br>
Relative: <b>home/myDir/</b><br>
filename: <b>image</b><br>
extension: <b>jpg</b><br>
<br>

<h2>Using</h2>

<pre class="code">
&lt;?php
/**
* @orm tableName sampleclass
*/
class MySampleClass extends DomArObject {
	/**
	* @orm plugin DomArFile({autoRename='myDir/$className/s_$id-$propertyName'})
	*/
	protected $myFile;
}

$o = new MySampleClass();
// add uploaded file
$o->myFile->addUploaded( $path, $name, $newRelativePath=NULL, $deleteIfExists=false );
// add existing file
$o->myFile->addExisting( $path, $newRelativePath=NULL, $deleteIfExists=false, );
// delete / unlink
$o->myFile->unlink();
?&gt;
</pre>

<h2>Rename</h2>
Renames file relative dir. File location must be relative to root path. If you add filename that will also be changed.
<pre class="code">
&lt;?php
$file->rename('newFileName');
$file->rename('newFileName.newExtension');
$file->rename('/newFileName.newExtension'); //move file to rootPath with newName.
$file->rename('newPath/to/file/');
$file->rename('newPath/to/file/newName');
$file->rename('newPath/to/file/newName.asdf'); //everything after one dot is considered extension. So this will rename file to newName.asdf NOT to newName.asdf.txt
$file->rename('newPath/to/file/newName.txt');
?&gt;
</pre>


<h2>Listeners</h2>
There are currently two possible listeners: beforeAdd, afterAdd<br>
<pre class="code">
&lt;?php
/**
* @orm tableName sampleclass
*/
class MySampleClass extends DomArObject {
	/**
	* @orm plugin DomArFile()
	* @orm listener beforeAdd beforeAddMyFile(ARG1)
	* @orm listener afterAdd afterAddMyFile(ARG1)
	*/
	protected $myFile;
	
	public function beforeAddMyFile( &$path, $ARG1) {
	
	}
	
	public function afterAddMyFile( $ARG1 ) {
	
	}
}
?&gt;
</pre>




<h2>Auto rename</h2>

Auto renames file name using parent id, className and property name. Mask is used to define renaming format.<br>
You can use these elements in mask:<br>
<ul>
	<li>$className - will be replaced by className</li>
	<li>$id - will be replaced by parents id</li>
	<li>$idTree - will construct a catalogue tree using $id. Tree will be something like millions/thousands/id. For example item with id 1234567 would be 1/234/1234567. Use this if you expect lots of files.</li>
	<li>$propertyName - will be replaced by property name</li>
	<li>$rand - will be replaced by random number. Useful if files are updated then each time they get new name, so browsers wont have them in cahce.</li>
	<li>$method(methodName) - calls a method for the object and expects string as a result. This string may contain other keywords like $id, $className etc except $method itself. This is very useful when you need to make custom partitions for keeping the files - for example over id 150000, store files to another server disk.</li>
</ul>
<br>

<h3>Masks:</h3> <br>
<table cellpadding="4" cellspacing="0" border="1">
	<tr>
		<td>1</td>
		<td>Uses mask: $className/$id-$propertyName</td>
	</tr>
	<tr>
		<td>1r</td>
		<td>Uses mask: $className/$id-$propertyName-$rand</td>
	</tr>
	<tr>
		<td>2</td>
		<td>Uses mask: $className/$id/$propertyName</td>
	</tr>
	<tr>
		<td>2r</td>
		<td>Uses mask: $className/$id/$propertyName-$rand</td>
	</tr>
	<tr>
		<td>idTree</td>
		<td>Uses mask: $className/$idTree/$id/$propertyName</td>
	</tr>
	<tr>
		<td>idTreeR</td>
		<td>Uses mask: $className/$idTree/$id/$propertyName-$rand</td>
	</tr>
	<tr>
		<td>(String)Custom mask</td>
		<td>You can define custom mask using mask elements. For example: 'myDir/$className/s_$id-$propertyName'</td>
	</tr>
</table>


<h3>Sample</h3>

<pre class="code">
&lt;?php
/**
* @orm tableName sampleclass
*/
class MySampleClass extends DomArObject {
	/**
	* @orm plugin DomArFile({autoRename='myDir/$className/s_$id-$propertyName'})
	*/
	protected $myFile;
}

$o = new MySampleClass();
// will move file to root url with  the same name as it currently has.
$o->myFile->addExisting('Some file path.txt');


$o->save(); // for example after save id=2
// renames file to this: ROOT/myDir/MySampleClass/s_2-myFile.txt

?&gt;
</pre>


<h3>Method sample</h3>

<pre class="code">
&lt;?php
/**
* @orm tableName sampleclass
*/
class MySampleClass extends DomArObject {
	/**
	* @orm plugin DomArFile({autoRename='$method(getStoragePath)'})
	*/
	protected $myFile;
	
	public function getStoragePath() {
		$path = '';
		if( $this->id  > 150000 ) {
			$path = 'hardDrive2';
		} else {
			$path = 'hardDrive1';
		}
		return $path.'/$className/$idTree/$id/$propertyName'; // Be sure to use apostrophe, not quotation marks!
	}
}
?&gt;
</pre>


{/literal}